FORTH 



The following pages begin an introduction to the 
language FORTH . This section of the manual should 
familiarise you with stack operations, simple integer 
calculations and elementary programming development. 
For more comprehensive programming, the magazines or 
books in the reference list should be consulted. 



Using FORTH : 1) Switch your computer on 

2) You should see a display including 
the words FORTH 1.1 

3) Press F 

4) The message Pegasus 6809 FORTH 
should appear 

5) Now you are ready to begin reading 
the FORTH manual. 

To EXIT FORTH 1) Type MON (press RETURN) 

2) You are now back to the Select mode 



TO REENTER FORTH 



1) You should be in the Select mode 

2) Type M 

G 0011. ( the . should return 
you to FORTH) 

3) ONLY use this method if you have 
previously been in FORTE since switch on 



panic: 



1) If for some reason (usually an illegal 
loop operation) the computer 'hangs-up' 
and will not respond, all is not lost. 
Press the NMI, button inside the computer 
and then reenter FORTH as above. 
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PEGASUS FORTH 



FORTH is quite different in structure from 
languages such as Basic or Pascal. FORTH begins 
with a set of defined WORDS in a DICTIONARY. 
Creating a program involves using these WORDS to 
define new WORDS which may be linked together to 
perform some task. For example, to display a chart 
of numbers on the screen, WORDS would be defined to 
print headings, to calculate results, and to print 
these results in columns. The word CHART would use 
all these words in its definition to perform the total 
task. 

The FORTH HANDY REFERENCE and the FORTH 
DICTIONARY WORDS sections list and explain the uses 
of the FORTH words available when the computer is put 
into the FORTH language. 
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A "entle Introduction to Pegasus Forth 

Forth as a language is very different from most 
other computer languages, such as Basic or Pascal. It 
requires a structured approach, ( having no GOTO state- 
ment ) , yet has all the convenience of an interactive 
interpreter. An expert's definition of Forth might be: 
threaded, extensible, interactive, tree-structured, 
self -implementing, interpretive language. 

Stack Concepts 

Forth is a stack language. A stack can be 
defined as a collection of data items, usually byte 
(8 bit) or work (16 bit) quantities, which are pointed 
to by a register known as a stack pointer, and are 
arranged so that the last item placed on to the stack 
is the first to be removed. Stacks usually grow from 
high memory addresses down to low memory addresses, 
and are contiguous. 

Any form of data may be placed on a stack, including 
number, characters, or addresses which point to data. If 
you have used a calculator with Reverse Polish Notation 
(RPN, e.g. Hewlett Packard), you will be at home with 
Forth. Such a calculator operates something like Forth 
in its use of a stack, and post-fix notation (or RPN) , 
to evaluate expressions. 

For instance, to evaluate (3*4)+ (6*2), where the 
asterisk '*' is the standard computer symbol for 
multiplication, we would enter into the computer: 

3 4*62*+. (press RETURN) 
with a space separating each symbol, or word. 

Evaluating from left to right: 3 is stacked, then 
4, then the multiplication operator multiplies the two 
numbers, removing them from the stack, and leaving 12 
on the top. Then 6 and 2 are stacked and multiplied, 
leaving another 12 on top of the 12 already there. The 
two products are then added, leaving 24 on the stack, 
which is then removed from the stack and printed with 
the ' . ' operator . 
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After the RETURN key is typed, the computer will 
respond 

24 OK 
It is a convention with Forth that when the top item 
of the stack is operated upon, then it is destroyed. 

Forth has two stacks - the variable S stack, 
which is used for passing data to operations, and the 
return stack, R, which is reserved for passing return 
addresses, as well as maintaining parameters for loop 
variables and controlling program flow. The S and R 
stacks occupy different regions of memory, although 
data may be passed between them. 

When typing in numbers or Forth words to the 
Forth input interpreter, separated by spaces, each 
data item is placed onto the S stack, starting from 
left to right. 

The S and R stacks are primarily used for internal 
communications within the Forth system. Most Forth 
operations communicate only through a stack. 

Dictionary 

The aspect of Forth which gives it its great 
power and extensibility is the Dictionary, which contains 
the definitions of the vocabulary items. Nearly all of 
Forth consists of Dictionary entries. Each entry is 
either machine code, or a variable length list of 
addresses pointing to other Dictionary entries. The 
Dictionary is extensible, growing upwards towards high 
memory. In the Pegasus, most of the Dictionary resides 
in EPROM, with any ^extensions occuring in RAM. 

The user may extend the Dictionary by defining 
new entries at the terminal. New entries may consist of 
standard words, or previously defined user words. New 
entries may also have the same name as previous entries, 
in which case they are considered to redefine the 
previous word. For instance, the addition operator, +, 
may be redefined as multiplication, *, leading to results 
like 

3 4+. 12 OK 



;s 
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Programming 

Now we come to writing the program itself. 
Firstly, the problem is broken down into all it! 
constituent sub-tasks through a process called "step- 
wise refinement'. Each subtask is then defined as a 
Forth word, in terms of words previously defined. 
Then build modules upwards by defining more words, 
until finally the last word that you define is the 
name of the program itself. 



As an example, let's write a small program to 
evaluate the polynomial 

3x 2 + 4x - 7 

for x=2 and x=7 

We type in the following: 

: POLY DUP DUP * 3 * SWAP 4 * + 7 - . ; 

The colon word * : ' means that a definition is to 

follow - the definition is terminated by the semicolon 

word ' ; ' . 

POLY is the name of the Forth word that we are defining 

- any name of up to 31 characters is acceptable here, 

and it can include any character except the space or 

RETURN, including control codes or special punctuation 

characters. 

DUP is a Forth word that duplicates the top stack, 
and leaves the result on the stack. Executed twice, 
this makes two copies of the number on the top of the 
S stack. 

The * operator is used to multiply these two copies, 
destroying them and leaving the result on top. The 
result is then multiplied by 3, leaving a new result, 
then SWAPped with the original number, x, which is 
multiplied by 4. Then the two terms are added, 7 is 
subtracted, and the result printed. 
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The program is now written, so let's run it: 

2 POLY (CR) 13 OK 

7 POLY (CR) 168 OK 

It's as simple as that! 
POLY is now a Forth word, that will be there until we 
turn off the Pegasus, or until we tell it to 

FORGET POLY (CR) 
in which case all definitions subsequent to and 
including POLY will be destroyed (unless they are 
saved on cassette first) . 

Forth Program to generate first n Fibonacci Numbers 

: FIBO 1+0 SWAP 1 SWAP 1 
DO CR DUP . SWAP OVER + 
LOOP ; 

To run program, simply enter number of terms to 
generate, and invoke, e.g. for 10 terms, enter 
10 FIBO (press RETURN) 



v 
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FORTH 

Please note that the following pages; E - 7. I to 
E - 7.5 inclusive will only apply when used with 
the cassette "Forth Stack Operations" which can be 
obtained from your dealer. 

STACK OPERATIONS (Please see next page for loading 
cassette instructions and program 
commands) . 

This section describes, with the aid of a FORTH 
cassette program, some of the operations available 
in handling numbers on the FORTH variable S Stack. 
The S Stack is used during calculations; the return 
stack R (used for loops and program flow) will not be - 
discussed in this section. 

VARIABLE STACK 

This Stack is a storage place for numbers used during 
a FORTH program. When a number is entered, it is 
placed on the top of the stack. When another number 
is entered, the new number is placed on the top after 
the previous numbers are pushed down. 

CASSETTE PROGRAM ; STACK OPERATIONS 

Onlythetop 5 locations of the stack will be shown. 

The total number of locations available depends on 

the computer memory size. 

Load the FORTH program "STACK OPERATIONS" 

Type in BEGIN STACK ( then press RETURN ) 

When OK and the flashing cursor appear, the program is 

ready to enter numbers. 

Type 5 (press RETURN) 
Observe how 5 is placed on the stack 

(press CTRL and U at the same time to clear the cursor's 
line) 
Enter these numbers in the same way: 
6 10 X 
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The stack should now show 2 

10 

6 

5 


You are now ready to experiment with the words in 
the Operation List. Only the upper case letters 
should be typed (e.g. DUP, ROT etc) . 

Loading Cassette Program : 

1) Power up PEGASUS 

2) Type F to select FORTH 1.1 

3) Type LOAD , press PLAY on your recorder 

press RETURN on the keyboard 

4) When the program has loaded successfully, the 
display should show F STACK LOADED . Turn off 
your recorder. 

Starting the Program : 

Type BEGIN STACK then press RETURN 

To Clear the Stack Display : 

Type CLEAR (then press RETURN) Zeros 
will be displayed on the stack. 

To Redisplay the Stack 

If some error has caused the display to scroll 
v up, then type WST (press RETURN) to display 
the stack again, with the latest values on the 
stack. 

To EXIT the Program : 

1) If you wish to permanently leave the program, press 
the computer's NMI button, (located inside the 
computer box ) 

2) If you wish to use FORTH type CLS FORTH (then press 
RETURN) 

To begin the stack program again, type BEGIN STACK 

(press RETURN) 

NOTE : THE NEGATIVE SIGN - IS AN UNSKIFTED KEY; the 
shifted key is NOT a negative sign or minus but 
an underline. 
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The following is only a suggested exercise before 
experimenting yourself with the stack. 

Type in one line at a time and observe each operation 
(Remember to delete the cursor's line, use CTRL U) 



DROP 

•DUP 

DROP 

SWAP 

OVER 

ROT 

+ 
SWAP 



/ 



2 removed 

10 copies 

top 10 removed 

10 and 6 change places 

10 copied and put on top 

Third number put on top 

Top two numbers added 

Top number subtracted from 
second 

Top two numbers multiplied 

2 entered 

Second number divided by top 



Enter numbers and use operations in any order you 
wish until you understand fully each operation. 



NOTE : 

Numbers for -20 to 20 are entered automatically (For 
numbers outside this range, please type E after each 
number e.g. 105 E 61 E ONLY during this cassette 
program) 

You may use 2 or more operations on the same line 
(e.g. 12 3 + DUP) 

Type F to speed up the display, S to slow down the display 
Multiple F's or S's may be used, each separated by a space. 
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You are now ready to attempt these exercises. 
(Answers on next page) 

1) Enter 12 3 4 5 onto the stack 

Which operation would you use to get 

(a) 4 then (b) 3 then (c) 3 then (d) 6 

5 4 3 4 

3 5 4 5 

2 2 5 2 

1 1 2 1 

2) Enter 12 3 4 5 again 

Which two operations would you use to get 
(a) 4 then (b) 4 then (c) 3 

5 5 9 

5 3 3 

3 2 2 

2 1 1 

3) Use the stack to do these calculations (enter the 
numbers in the correct order and then do the operation) 

(a) 6+2 

(b) 6-2 
(c-) 6*2 

(d) 6-2 (use / for division) 

4) Use the stack to find (do multiplication before 
addition) 

(a) 5*2+3 

(b) 5 + 2*3 



K - 7.5 16/7/61 



ANSWERS 

1. (a) SWAP (b) ROT (c) DUP (d) ,+ 

2. (a) DUP ROT (b) ROT DROP (c) + OVER 

3. (a) 6 2 + (b) 5 2 - (c) 6 2 * (d) 6 2 / 

4. (a) 3 5 2 * + (b) 5 2 3 * + 



V 
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Arithmetic Operations 

In normal operation, this version of FORTH uses 
16-bit signed arithmetic which allows integers from 
-32768 to +32767 to be used. You can develop methods 
to work with numbers outside this range, but only this 
range will be assumed for now. 



CALCULATIONS 

Reverse Polish Notation (RPN) is used in calculations. 
For Example: 

6 + 5 * 2 is entered as 5 2*6+ 

(Note: * is the symbol for multiplication) 

( * is done before + ) 

To print the answer, (which is stored on top of the 
stack) the FORTH word . is used ( i.e. a full stop) 

Type in 5 2*6+. 

The answer 16 should be printed in the same line 

followed by OK. 

Exercises : (The answers are on the following page) 

Change these operations to RPN; then use FORTH to 
print the answers. 

(a) 7*2 + 3 + 4 

(b) 7*2 + 3*4 

(c) 7 * (2 + 3) * 4 

(d) 72-9 ( use / on the keyboard for division ) 

(e) (64 + 6) - 7 
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ANSWERS 

(a) 7 2* 3 + 4 + . 

(b) 7 2 * 3 4*+ . 

(c) 23+7*4*. (+ adds the 2 and 3 ) 

{ first * multiplies the 
answer by 7) 

( second * then multiplies 

by 4 ) 



(d) 72 9 / . 

(e) 64 6 + 7 / 



Note ; Other answers are possible. For example (a) 
could be done 
3 4 7 2* + +. 

In this case, all numbers were put on the stack, 
v and then the operations were performed. 



Similarly: (c) 7 4 2 3+**. 
(e) 7 64 6 + / . 
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PROGRAM MING ADVICE 

A list of FORTH WORDS is given in the FORTH HANDY 
REFERENCE pages . 

A new WORD may be defined using previously defined 

words by using : to begin a definition (leave a 
space after the colon) 

; to end the definition 



EXAMPIK: 



CK 16 EMIT ; to display the clock 
CK is the new word to be defined. 
To use the word, type CK 



A WORD can be any string of up to 31 characters 

bounded by spaces. 

Keep WORDS simple in operation. Test each new 

word after you define it. Then build further words 

from these simpler words until the full TASK is 

developed. 

All FORTH WORDS must be bounded by spaces. 

For numbers 5 2 6 enters three numbers 

5 26 enters two numbers ( 5 and 26 ) 



sdhE FORTH MESSAGE STATEMENTS 



WORD NOT FOUND 



You have not defined a word used 
or you have misspelt the word 



REDEF: ISN'T UNIQUE 



Just a warning that a word has 
been defined before. You may 
continue with the new definition. 



CONDITIONALS NOT PAIRED 



You forgot one of the words that 
are used to end DO , IF, or BEGIN 
structures. 
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CASSETTE SAVE & LOAD 



To SAVE the FORTH words you have defined - 

1. Check that the recorder is properly attached 
to your PEGASUS 

2. Type SAVE (press RETURN) 

3. The screen will display FILENAME? 

4. Type in the name of your program (8 characters 
maximum) DO NOT PRESS RETURN YET 

5. Press RECORD & PLAY on you recorder and then 
press RETURN on the keyboard. 

6. The screen display will be blank during the 
SAVE operation. 

7. When the display returns, turn off the 
recorder. Your FORTH words are now saved. 



To LOAD a FORTH cassette - 

1. Check that the recorder is properly attached 
to your PEGASUS and that the volume control 
is at a suitable level. (you may have to 

make some initial adjustments for a proper LOAD, 
but once this level has been determined, keep 
the level at that point) 

2. Type LOAD DO NOT PRESS RETURN 

3. Depress PLAY on your recorder and then press 
RETURN on the keyboard. 

4. The screen will be blank during the load 
v operation. 

5. When the display returns, your program should 
be loaded. Turn off your recorder. 

6. If the program did not load, then begin at 1 
above. The most probable cause for a faulty 
load is an incorrect volume level. 
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FORTE HANDY REFERENCE 



Operand key: 



n, nl 
d, dl 

u 

addr 

b 

c 

f 



16-bit signed numbers 

32-bit signed numbers 

16-bit unsigned number 

address 

8-bit byte 

7-bit ascii character value 

boolean flaa 



STACK MANIPULATION 



DUP 

DROP 
SWAP 

OVER 

ROT 

-DUP 

>R 

R> 
R 



( n - n n ) 

{ n - ) 

( nl n2 - n2 nl ) 



Duplicate top of stack 
Throw away top of stack 
Reverse top two stack 
items 4 

( nl n2 - nl n2 nl ) Make copy of second 

item on top 

( nl n2 r.3 - n2 n3 nl ) Rotate third item 

on top 

( n - n ? ) Duplicate only if non- 

zero 

( n - ) Move top item to "return 

stack" for temporary 
storage (use caution) 

( - n ) Retrieve item from return 

stack 

( - n ) Copy top of return stack 

onto stack 



NUMBER BASES 

DECIMAL 

HEX 

BASE 



( - ) 
( - ) 
( - addr ) 



Set decimal base 
Set hexadecimal base 
System variable contain- 
ing number base 



ARITHMETIC AND LOGICAL 



+ 
D+ 



/ 

MOD 

/MOD 
./MOD 



( nl n2 - sum ) Add 

( dl d2 - sum ) Add double-precision 

numbers 

( nl n2 - diff > Subtract (nl-n2) 

( nl n2 - prod ) Multiply 

( nl n2 - quot ) Divide (nl/n2) 

( nl n2 - rem ) Modulo (i.e. remainder 

from division) 

( nl n2 - rem quot ) Divide, giving remainder 

and quotient 

( nl n2 n3 - rem quot ) Multiply, then divide 

(nl.n2/n3), with double- 
precision intermediate 
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Stock Inpuls end outputs at e shown; (Dp of stack on r iCjhl. 
This card follows usage ol the Forth Interest Group 
(S.F. Bay Atcb); usage aligned with the Forth 76 
International SlandBid. 
For more Into: Folh Into est Group 
P.O. Bo* 1105 
San Carlos, CA 94070. 



OpersncSkof' n, nl, ID-bit sic nod number* 



d. dl. 



addr 



32-bit signed numbers 

16-blt unsigned number 

address 

e-blt byle 

7-bII ascll character value 

boolean (lag 



STACK MANIPULATION 

OUP ( n - n n ) - 

DROP ( n - ) 

SWAP [ nt n 2 - n2 nl ) 

OVER |nl n2 - n1 n2 nl } 

ROT 

-OUP 

>R 



R> 
R 



Duplicate (op of alack. 

Throw away lop of alack. 

Rc-verbc lop two a: rick lt«ms. 

(.ink t: copy of second Ittm on top. 
{ nl n2 r3 - n2 n3 nl ) Ftotale third lie m to top. 
{ n — n ? ) Duplicate only If non-iero. 

n — ) Move top Item to "return stack" for lemporory storage (use caution). 



< - n) 

< - it ) 



Retrieve item from ret jrn stack. 
Copy lop Of return stack onlo stack. 



NUMBER BASES 

DECIMAL ( - | 

HEX ( - ) 

BASE ( - addr ) 



Set decimal base. 

Set hexadecimal base. 

System variable containing number base. 



ARITHMETIC AND LOGICAL 



+ 

D+ 



/ 

MOD 

/MOD 

•/MOD 

V 

MAX 

MIN 

ABS 

DABS 

MINUS 

DMINUS 

AND 

OH 

XOR 



(nl 

(dl 

(nl 

<n1 

(nl 

(n1 

(nl 

(nl 

(nl 

(nl 

( "I 

(n 

( d 

( r> 

( d 

(nl 

( nl 

(nl 



n2 — sum ) 

d2 — sum ) 

n2 - diff ) 

n2 — prod ) 

n2 — quot ) 

n2 — rem J 

n2 — rem quot ) 

r>2 n3 — rem quot ) 

n2 n3 — quot ) 

n2 — max ) 

r>2 - mln ) 

■ absolute ) 

- absolute ) 

- -n ) 

- -d) 
n2 — and ) 
n2 - or ) 
n2 — xoi ) 



Add. 

Add double-precision numbers. 

Subtract (nt-n2). 

Multiply, 

Divide (n1/n2). 

Modulo (/. s. remainder (rom division). 

Divide, giving remainder and quotient. 

Multiply, then divide (nfn2/n3). with double -precision Intermediate. 

Uke •/MOD, but give quotient only. 

Maximum. 

Minimum. 

Absolute vbIub. 

Absolute value of double-precision number. 

Change sign. 

Change sign of double-precision number. 

Logical ANO (bitwise). 

Logical OR (bitwise). 

Logical exclusive OR (bitwise). 



COMPARISON 



G>< 
0*= 



( nl n2 - f ) 
( n1 n2 - C ) 
( nl n2 - I ) 
(n - f ) 
( n - I ) 



True if nl less than n2. 

True It nl greater than n2. 

True If top two numbers are equal. 

True If top number negative. 

True If lop number zero [I.e., reverses truth value). 



MEMORY 




*? 


( addr - n ) 


i 


( n sddr — } 


ce> 


( addr — b ) 


CI 


( b addr — ) 


? 


(eddr - } 


+i 


( n addr — ) 


CMOVE 


( from to u — 


FILL 


( addr u b — 


ERASE 


f-eddr O - ) 


BLANKS 


( addr u — ) : 



Replace word address by contents. 

Store second word at address on lop. 

Fetch one byte only. 

Store one byte only. 

Print contents of address. 

Add second number on slack to contents of address on top. 

Move u bytes in memory. 

Fill u bytes in memory with b, beginning si address. 

FTII u bytes In memory with zeroes, beginning at address. 

Fill u bytes in memory with blanks, beginning at eddress. 



CONTROL STRUCTURES 



DO ...LOOP 
I 

LEAVE 

DO . . . + LOOP 

IF . . . (true) . . . ENDIF 
IF . . . (true) . . . ELSE 

...(false)... ENDIF 
lirGlN .. . UNIU 
lit. GIN . . . WMIl.l. 

. . . REPEAT 



do: ( end+-1 start 
{ - index ) 
(■•.-• )- 

do: { end+1 start 
+loop: ( n — ) 
H: ( f - | 
if: ( I ~ | 



— ) Setup loop, given index range. 

Place currenl index value on stack. 
Terminate loop at next LOOP or +LOOP. 

— ) Uke DO . . . LOOP, but adds stack value (instead ol always "1 *) to index. 

K top ol stack true (non-zero), execute. (Nole: Faith 76 uses IF . . . THEN.) 
Same, but if lalse. execute ELSE clause. (Note: Forth 76 uses IF . . . ELSE . . . THEN ) 



unl.l < I - 
wh.le: { I - 



Loop brick lo IH.GIN until tru« at UNI II. [Noli- Form TB uses 11 FTC IN 
Loop while true at WHILE: REPEAT loops unconditionally lo ULGIN 
(Note: forth 7e uses BEGIN . . . « . . .AGAIN J 



END) 
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./ 

MAX 
MIN 
ABS 
DABS 



MINUS 
DMINUS 

AND 

OR 

XOR 



( nl n2 n3 - quot ) 

( nl n2 - max ) 
( nl n2 - min ) 
( n - absolute ) 
( d - absolute ) 



( n - -n ) 
( d - -d ) 

( nl n2 - and ) 
( nl n2 - or ) 
( nl n2 - xor ) 



Like ./MOD but give 
quotient only 

Maximum 
Minimum 
Absolute value 
Absolute value of 
double-precision 
number 
Change sign 
Change sign of double- 
precision number 
Logical AND (bitwise) 
Logical OR (bitwise) 
Logical exclusive OR 
(bitwise) 



COMPARISON 



o--- 



( nl n2 - f ) 
( nl n2 - f ) 
( nl n2 - f ) 
( n - f ) 
( n - f ) 



True if nl less than 
n2 

True if nl greater than 
n2 

True if top two numbers 
are equal 
True if top number 
negative 

True if top number zero 
(i.e., reverses truth 
value) 



MEMORY 



C^ 
Ci 



+ : 



CMOVE 
FILL 



ERASE 



BLANKS 



( addr - n ) 

( n addr - ) 

( addr - b ) 
( b addr - ) 
( addr - ) 
( n addr - ) 



( from to U - ) 
( addr u b - ) 

( addr u - ) 



( addr u - ) 



Replace word address by 

contents 

Store second word at 

address on top 

Fetch one byte only 

Store one byte only 

Print contents of address 

Add second number on stack 

to contents of address on 

top 

Move u bytes in memory 

Fill u bytes in memory with 

b beginning at address 

Fill u bytes in memory 

with zeroes, beginning at 

address 

Fill u bytes in memory 

with blanks, beginning 

at address 
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CONTROL STRUCTURES 



DO . . . LOOP 



LEAVE 
DO..-.+LOOP 



IF.. . (true) 
. . .ENDIF 

IF. . . (true) 
.. .ELSE 

.. . (false) 

.. .ENDIF 
BEGIN. . .UNTIL 



BEGIN WHILE 

. . . REPEAT 



TERMINAL INPUT-OUTP'JT 



do: ( end+1 start 

( - index ) 

( - ) 

do: ( end+1 start 
+loop: ( n - ) 





( 


n 


- ) 




.R 


( 


n 


fieldwidth - ) 


D. 


( 


d 


- ) 




D.R 


( 


d 


fieldwidth - ) 


v 










CR 


( 


- 


) 




SPACE 


( 


- 


) 




SPACES 


( 


n 


- ) 




# " 


( 


- 


) 




DUMP 


( 


addr u 


- ) 


TYPE 


( 


addr u 


- ) 


COUNT 


( 


addr - 


addr+1 u ) 


KEY 


( 


- 


c ) 




EMIT 


( 


c 


- ) 




EXPECT 


( 


addr n 


- ) 



) Set up loop, given 
index range 
Place current index 
value on stack 
Terminate loop at next 
LOOP or +LOOP 

) LikeDO. . .LOOP, but adds 
stack value (instead of 
always ■ 1 ' ) to index 
If top of stack true 
(non-zero) execute (Note: 
Forth 78 uses IF... THEN) 
Same but if false, execute 
ELSE clause. (Note: Forth 
78 uses IF. ..ELSE. . .THEN) 

Loop back to BEGIN until w 
true at UNTIL (Notes 
Forth 78 uses BEGIN... 
END) 

Loop while true at WHILE, 
REPEAT loops uncondition- 
ally to BEGIN (Note: 
Forth 78 uses BEGIN... IF 
. . .AGAIN) 



Print number 
Print number, right 
justified in field 
Print double-precision 
number 

Print double-precision 
number, right- justified 
in field 

Do a carriage return 
Type one space 
Type n spaces 
Print message (terminated 
by ") 

Dump u words starting at 
address 

Type string of u charac- 
ters starting at address 
Change length-byte strinq 
to TYPE form 

Read key, put ascii value 
on stack 

Type ascii value from stack 
Read n characters ( or until 
carriage return) from input 
to address 
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INPUT-OUTPUT FORMATTING 



NUMBER 

<* 
* 



*S 

SIGN 
* 

HOLD 



( addr - d ) 



( - ) . 
( d - d ) 



( d - ) 

( n d - d ) 
( d - addr u ) 
C c - ) 



Convert string at address 
to double precision 
number 

Start output string 
Convert next digit of 
double precision number 
and add character to 
output string 
Convert all significant 
digits of double prevision 
number to output string 
Insert sign of n into 
output string 
Terminate output string 
(ready for TYPE) 
Insert ascii character 
into output string 



DEFINING WORDS 

: xxx ( - ) 

; ( - ) 

VARIABLE xxx ( n ' - ) 

xxx: ( - addr ) 



CONSTANT xxx ( n - ) 

xxx: ( - n 



BUILDS. . 
DOES 



V, 



does: ( - addr ) 



Begin colon definition 

of xxx 

End colon definition 

Create a variable named 

xxx with initial value n; 

returns address when 

executed 

Create a constant 

named xxx with value n; 

returns value when 

executed 

Used to create a new 

defining word, with 

execution- time routine for 

this data type in higher 

level Forth 



VOCABULARIES 

CONTEXT ( - addr ) 



CURRENT 



FORTH 



( - addr ) 



C - ) 



DEFINITIONS ( - ) 
VOCABULARY xxx ( - ) 
VLIST ( - ) 



Returns address of 
pointer to context 
vocabulary (searched 1st) 
Returns address of 
pointer to current 
vocabulary (where new 
definitions are put) 
Main Forth vocabulary 
(execution of FORTH 
sets CONTEXT vocabulary) 
Sets CURRENT vocabulary 

to CONTEXT 

Create new vocabulary 

named xxx 

Print names of all words 

in CONTEXT vocabulary 
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TERMINAL INPUT-OUTPUT 



R 

D. 

D.R 

CR 

SPACE 
SPACES 

DUMP 
TYPE 
COUNT 

KEY 

EMIT 
E-XPfcCT 



( n - ) 

( n lield«idlh - ) 

{d - ) 

( d lieldwidth - ) 

( - ) 

( - ) 

(n - ) 

A •"* J 

(^addr u — ) 
' ( addf u - ) 
( sddr - eddr+1 u ) 

( - c ) 

U- ) 

( addr n - ) 



Print number. 

Prlnl nu-nbor. right-justllied In field. 

Print doublo-precislon number. 

Pilnl double -precision number. right-Juslified in field 

Do b CBiriago relum. 

Type one space. 

Type n spaces. 

Print message (terminated by "). 

Dump u words starling at addiess. 

Type siring ol u characters sterling at address. 

•Change length-byte siring lo TYPE lorm, • 

Read key, put ascii value on stack. 

Type ascli value from slack. 

Read n characters (or until carriage return) Irom Input lo address. 



INPUT-OUTPUT FORMATTING 



NUMBER 


( oddr - d ) 


<# 


( - ) 


« 


(d-d) 


«S 


( d - O ) 


SIGN 


(nd-d) 


*> 


( d — addr u ) 


HOLD 


< c - ) 



Convert string et address lo double-precision number. 

Start output siring. 

Convert next digit ol double -precision njmber and add characler to output string. 

Convert all signilicanl digits ot double-precision number to output string 

Insert sign ol n Into output string. 

Terminate output siring (ready for TYPE). 

Insert ascii character into output siring. 



DISK HANDLING 

IIST 

LOAD 

BLOCK 

B/BJF 

BLK 

SCR 

UPDATE 

ausH 

EMPTY-BUFFERS 



(To be available later) 

screen — ) List 8 disk screen. 

screen — ) Load disk screen (compile or execute). 

block — addr ) ReBd disk block to memory address. 

— n ) System constant giving disk block size in bytes 

— addr ) System variable containing current block number. 

— addr ) System variable containing currenl screen number. 

— ) Mark last bullet accessed as updated. 

— ) Write all updated buffers to disk. 

— ) Erase all bullers. 



DEFINING WORDS 



VARIABLE xxx 

CONSTANT xxx 

CODE xxx 
;CODE 



( - ) 
( - > 

(n - ) 

xxx: ( — addr ) 
(n- ) 

xxx: ( — n ) 
( - ) 
( - ) 



<BUILDS . . . DOES> does: ( - addr ) 



Begin colon definition of xxx. 

End colon delinition. 

Create a variable named xxx with initial value n: returns address when executed. 

Create a constant named xxx with value n: returns value when executed. 

Begin definition ol assembly-language primitive operation named xxx. 
' Used to creale a new delining word, with execution-time "code routine" for this data 

type in assembly. 
Used to creale a new defining word, with execution-time routine lor this data type in 
higher-level Forth. 



VOCABULARIES 

CONTEXT ( - addr ) 

CURRENT ( - addr ) 

FORTH ( - ) 



Returns address of pointer to context vocabulary (searched first) . 

Returns address Of pointer to current vocabulary (where new definitions are put). 

Main Forth vocabulary (execution of FORTH sets CONTEXT vocabulary). 



DEFINITIONS 


( - 


) 


VOCABULARY xxx 


( - 


) 


VLIST 


( - 


) 



Sets CURRENT vocabulary to CONTEXT. 

Creale new vocabulary named xxx. 

Print names ol all words in CONTEXT vocabulary. 



MISCELLANEOUS AND SYSTEM 



( 


- ) 


FORGET xxx 


- > 


ABORT 


- ) 


• xxx 


- addr ) 


HERE 


— addr ) 


PAD 


- addr ) 


IN 


— addr ) 


SP6> 


— addr ) 


ALLOT 


n - ) 




n - ) 



Begin comment, terminated by right paren on same line; space after (. 

Forget all definitions back to and including xxx. 

Error termination of operation. 

Find the address of xxx in the dictionary; if used in delinition. compile address. 

Returns address of next unused byte in the dictionary. 

Returns address ol scratch area (usually 68 bytes beyond HERE) 

System variable containing offset into input butter; i ■ " - - 

Returns address ol top slack item. 

Leave a gap ol n bytes in the dictionary. 

Compile a number into the dictionary. 



Forth Interest Group, P.O. Box 1105, San Carlos, CA 94070 



■■ 
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MISCELLANEOUS AND SYSTEM 



( 
FORGET xxx 

ABORT 
xxx 



HERE 
PAD 

IN 

SP@ 
ALLOT 



- ) Begin comment, terminated by right 

paren on same line; sapce after (. 

- ) Forget all definitions back to and 

including xxx 

- ) Error termination of operation 

- addr )Find the address of xxx in the 

dictionary; if used in definition, 
compile address 

- addr ) Returns address of next unused 

byte in the dictionary 

- addr ) Returns address of scratch area 

(usually 68 bytes beyond HERE) . 

- addr ) System variable containing offset 

into input buffer 

- addr ) Returns address of top stack item 
n - ) Leave a gap of n bytes in the 

dictionary 
n - ) Compile a number into the 
dictionary 



v 
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New FORTH Words: (available from FORTH dictionary) 

CLS - screen clear 

CS - turn cursor on 

CSX - turn cursor off 

IV - turn inverse video on 

IVX - turn inverse video off 

U. - unsigned number print (range 

to 65535) 

U.R. - right justified unsigned print 



Available with FORTE 1.2 

CK - turn clock oh 

CKX - turn clock off 

H - enter hours 

M - enter minutes 

S - enter seconds ( enter as 6 H 24 M S ) 

PC - switch to programmable character RAM 

PCX - switch to normal characters 

DFORTH - prints the definition of a user FORTH 
word (see E - 39. Of or use and caution 
notes) 

See also E - 34 . to E - 38 . for EDITOR words available 
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FORTH PROGRAMMING: 



Screen Operations 



Although you nust understand how the stack operates 
to do calculations, you can do much more with FORTH 
than imitate a programmable calculator. This section 
will show you how to define words to output text, 
numbers and some graphics onto the screen. 

The FORTH word EMIT will output the ASCII number at 
the top of the stack to the screen. If the number 
is from 32 to 127 EMIT will put a letter, digit or 
other character onto the screen. Try typing in these 
commands to see how EMIT may be used. 



65 EMIT 
75 EMIT 
4 9 EMIT 
4 2 EMIT 



(press RETURN after each line) 



Look at the table ASCII characters. You should find 



the characters A K 1 
above. 



* beside the numbers used 



Use the word EMIT to put these characters on the 
screen: 

P P ) # 

If you use a number less than 32, one of the screen 
functions will be activated instead. Some of the 
functions are: 



Clear screen 12 EMIT 

Inverse video on 1 EMIT 

Cursor on 6 EMIT 

Clock display on 16 EMIT 

Set cursor position 11 EMIT 

Delete current line 21 EMIT 



Inverse video of 2 EMIT 
Cursor off 15 EMIT 
Clock display off 17 EMIT 



Try some of the above functions by using EMIT. 

You are now ready to define some of your own FORTH words. 

The colon : is used to begin a definition. IT MUST BE 

FOLLOWED BY A SPACE] 
A semi-colon ; ends the definition. 

The words to clear the screen, and turn the cursor and 

inverse video on and off have been included in the FORTH 

dictionary. Their symbols are CLS CS CSX IV IVX 
(see E - 13.0) 
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ASCII CHARACTER TABLE 



The members from to 31 are reserved for special 
screen function controls. 



CHARACTER 


ASCII 
(decimal) 


CHARACTER 


ASCII 
(decimal) 


CHARACTER 


ASCII 
(decimal) 




Space 


32 


, 


64 




96 




■ 


33 


A 


65 


a 


97 




n 


34 


B 


66 


b 


98 




1 


35 


C 


67 


c 


99 




$ 


3C 


D 


68 


d 


100 




% 


37 


E 


69 


e 


101 




& 


38 




70 


f 


102 




■ 


39 


G 


71 


g 


103 




( 


4C 


H 


72 


h 


104 




) 


41 


I 


73 


i 


105 




* 


42 


J 


74 


J 


106 




+ 


43 


K 


75 


k 


107 




/ 


44 


L 


76 


1 


108 




- 


45 


M 


77 


m 


109 




i 


46 


N 


78 


n 


110 




/ 


47 





79 


o 


111 







48 


P 


80 


P 


1 12 




1 


49 

50 


Q 

R 


81 
82 


q 

r 


113 




•v2 


114 




3 


51 


S 


83 


s 


115 




4 


52 


T 


84 


t 


116 




5 


53 


U 


85 


u 


117 




6 


54 


V 


86 


V 


118 




7 


55 


w 


87 


w 


119 


• 


8 


56 


X 


88 


X 


120 




9 


57 


Y 


89 


Y 


121 




: 


58 


n 


90 


z 


122 




; 


59 


[ 


91 


{ 


123 




< 


6C 


\ 


92 


! 


124 




= 


61 


] 


93 


1 


125 




> 


62 


A 


94 


126 




■? 


63 




95 


m 


127 





Note the difference between the digit and the 
letter O 
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Define these words by typing in the following- 
: CK 16 EMIT ; - displays the clock 
: CKX 17 EMIT ; - turn display off 
To use these words/ type CK {press RETURN) 

or CKX 



SCREEN DISPLAY - The screen has 16 lines, 32 columns 

wide. The figure below shows how 
these are numbered. 



Lines 



Columns 
1234567 



29 30 31 




If you want to put the cursor at column 20 of line 5 
you must use EMIT three times. 



11 EMIT. 



prepares to set 
position 



20 EMIT 



column 
number 



5 EMIT 



line 
number 



All this must be done even before you can put anything 
there. To put the letter 'A' (ASCII 65) at this 
position, type in: 

11 EMIT 20 EMIT 5 EMIT 65 EMIT 

sets position prints A 

A word CPOS has been included in the FORTH dictionary 
to set the cursor position. This word is defined as - 

: CPOS 11 EMIT SWAP EMIT EMIT ; 
Now to print A in column 20, lines 5, type: 
20 5 CPOS 6 5 E.MIT ( a bit easier?) 
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HOW AND WHY CPOS V70RKS : 

CPOS expects two numbers to be on the stack, the column 
number and the line number. 



Step 1 



STACK 

5 

20 

x 

x 



OPERATION 

- line number entered last 

- column number entered first 



Step 2 



Step 3 



11 
5 

20 
x 

5 

20 

x 

x 



CPOS 11 puts 11 on stack 



11 \ EMIT - first EMIT uses 11 to 

prepare to set the position 



Step 4 



20 
5 
x 

y- 



SWAP - 



we need column number 
first 



Step 5 



20 



->EMIT - column number now used 



Step 6 



-> EMIT - line number now used 



The stack has used the two numbers 20 and 5 to set the 
cursor position and it is now ready for further entries. 

Now, use CLS and then CPOS four times to put four x's, 
one below the other, starting at column 25 on line 4. 

You still have to type a lot to just to get one letter 
onto the screen. If you want several words, or a line 
of characters, there are other ways instead of using EMIT. 
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PRINTING TEXT 

is the FORTH word to print text. THERE IS NO 
SPACE BETWEEN . AND " BUT THERE IS AFTER " 
is the FORTH word to end the text printing. 

Example : Wl ." PEGASUS" ; is the definition of Wl 

to print PEGASUS 

Now to print PEGASUS starting at column 20, line 5, type 

20 5 CPOS Wl CR (the CR is used to begin a 
new line after printing) 

Let's define another new word to combine these words. 

: PRINT CPOS Wl CR ; 

This new word will expect two numbers, the column number 
and the line number. 

To use, type 20 5 PRINT 

EXERCISES (clear the screen after each exercise) 

1. Define a word PRINTl to print PEGASUS in inverse 
video. You may use IV and IVX to turn the inverse 
video on before printing and off afterwards. 

2. The FORTH word SPACES will put blanks on the screen. 

IV 9 SPACES IVX will put 9 inverse blanks (white 
blocks) on the screen. 

Use this information to define a word 9SP to put 9 
white blocks beginning at a specified column and line. 

3. Define a word TASK to print PEGASUS near the middle 
of the screen, in normal video, with a white border 
on v top, bottom, and sides. 

Break the task into several parts; define words and 
test them for each part. Then combine these words 
into the one word TASK which will do the entire 
operation. 

(Answers are on the following page) 
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POSSIBLE ANSWERS 



1. : PRINT1 CPOS IV WI IVX CR ; to use type 20 5 PRINTl 

2. : 9SP CPOS IV 9 SPACES IVX CR ; to use type 

20 5 9SP 

3. You should break this task into several parts. 



(a) 
(b) 



(c) 
(d) 



: T3 10 6 9SP ; - top border 

Define another word 

: ISP CPOS IV 1 SPACES IVX CR J 



NOTE - SPACES 



does not change 
Use ISP to provide the left and right borders. 
LB 10 7 ISP ; - left border 

RB 18 7 ISP ; - right border 

PG 11 7 PRINT ; - prints PEGASUS 

B3 10 8 9SP ; - bottom border 



Now put all these parts together 



: TASK CLS TB LB PG RB BB ; 



To use, type TASK 



V 
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COMBINING MATHS AND TEXT PRINTING 

This section will describe a task using defined words for 

(a) finding the cube of a number 

(b) calculating cubes of 10 numbers 

(c) printing headings and putting results in 
chart form 

(a) If you want to cube a number, you need 2 duplicate 
numbers to multiply with the original 

: CUBE DUP DUP * * ; 

Type 5 CUBE . (the . is needed to print the result). 

Check carefully how the definition of CUBE works. 

(NOTE: The stack can only store numbers from -32768 to 
32767 32 CUBE will cause stack to overflow) 

(b) We must use a DO LOOP to do a calculation 

more than once. Let's define a word to print the 
numbers from 1 to 10. 

: COUNT 11 1 DO I . CR LOOP ; 
Type CLS COUNT to test. 

How COUNT works 

11 1 - loop starts at 1 but stops at 10 , NOT 11 

DO - Start of Loop 

I . - prints this number 

CR - begins new line 

LOOP - end of loop 

When t^he list was printed, the of 10 was not in the one's 
column'. Redefine COUNT using 6 .R instead of . and try 
COUNT now. ( 6 .R - sets up a block ,of 6 spaces with the 
one's column on riqht. 

EXERCISE 

If we want to print a list of cubes, we can use a loop 
similar to COUNT. 

: 10 CUBES 11 1 DO I CUBE 6 .R CR LOOP ; 

The only difference is that I is cubed before it is 

printed. 

Next combine these ideas into one loop that will print 
number and its cube. 
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: CUBECHART 11 1 DO 4 SPACES J 6 .R 10 SPACES I CUBE 
6 . R CR LDCP ; 

4 SPACES provides spaces on the left margin of the chart; 

10 SPACES gives a gap between the numbers and their cubes. 

(c) Finally, we need a word to print a heading for each 
column. You can do this yourself. 

EXERCISE 

Use what you learned about text printing and CUBECHART 
to do the following. 

1. Clear the screen 

2. Print on line CUBES FROM 1 to 10 

3. Print on line 2 in inverse video 

NUMBER CUBE 

4 . Print columns for number and its cube 
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POSSIBLE ANSWERS 

: L0 .." CUBES FROM 1 to 10" ; 
Wl . " NUMBER" i 
W2 ." CUBE" ; 

L2 3 SPACES IV V71 IVX 13 SPACES IV W2 IVX ; 
CHART CLS L0 CR CR L2 CR CUBECHART ; 

Your answer may have different methods of printing line 

and 2. 

If it works, it's right I 



v 
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GUIDE TO DICTIONARY WORDS : 
(see E - 11.0 to E - 12.0 for summary) 



DEFINING WORDS E - 23.0 

MEMORY E - 24.0 

NUMBER BASES E - 26.0 

COMPARISON E - 27.0 

CONTROL STRUCTURES E - 2 8.0 

INPUT-OUTPUT E - 31.0 

MISCELLANEOUS E - 33.0 

DFORTH E - 39.0 

EDITOR E - 34.0 



v 
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FORTH DICTIONARY WORDS 



DEFINING WORDS 



(a) New words are defined with a COLON DEFINITION, 
: begins the definition 
; ends the definition 



Example: 



CK 16 EMIT 



(b) Variables may be stored for later use. 

VARIABLE NUM defines NUM with an initial 

value 



changes value to 25 

( ! is pronounced "store" ) 



puts the value of NUM onto the 
stack ( @ is .pronounced "fetch" ) 

NUM 



25 NUM 1 
NUM @ 

NUM ? prints the value o 

( NOTE- ? is the same as @ . ) 

(c) Constants may be defined for later use. 

50 CONSTANT N defines N with the initial value 50 

The value of N cannot be changed once it is defined. 
N puts the value of N onto the stack 

N . prints the value of N 

NOTE: Observe the differences in putting the values of 
variables and constants onto the stack and for 
printing their values. 



Definition 
Change value 
Value onto stack 
Print Value 



VARIABLE 
VARIABLE NUM 
25 NUM I 
NUM @ 
NUM § . 
or NUM ? 



CONSTANT 
50 CONSTANT N 
fixed value 
N 

N . 



.«■ 



E - 24.0 16/7/81 



MEMORY UTILISATION WORDS 

Each address location in the computer can store 1 byte 
of 8 bits . One byte can represent numbers from 

to 255; thus ASCII characters may be stored as 1 byte, 

1 cell is 2 bytes for a total of 16 bits. 

One cell can represent numbers from to 65535 or 

numbers from -32768 to 32767 
FORTH uses this last range of numbers 

IN MOST CASES: 1 byte is used for ASCII characters 
1 cell is used for numbers 



(a) @ (pronounced "fetch" ) 

§ replaces a memory address with the number in the 
cell starting at this address. 

C@ replaces an address with the contents in the 
byte at this address 

Examples: NUM @ NUM was defined as a location 

for a variable 

NUM puts the address on the stack. 
@ replaces this address with the 
value of the variable 

HEX BF00 C@ C@ replaces the hex address BFO0 
v with the value in this address. 

This value is now on the stack. 

(b) .' (pronounced "store" ) 

! and CI work in the same way as @ and C@ but contents 
are stored into cells or bytes. 
Examples: 25 NUM 1 

HEX 41 BFO0 CI (puts 41 (hex) into BF00) 
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(c) CMOVE is used to move bytes fron one address to 
another. 

The screen addresses are from: 
BEO0 to BFFF in HEX 
48640 to 49151 in DECIMAL 

HEX BE0O BF00 20 CMOVE moves 20 (hex) bytes starting 

at BE 00 to 20 (hex) bytes 
starting at BF00 . 

In DECIMAL the operation becomes: 
DECIMAL 48640 48896 32 CMOVE 

(e) FILL ERASE BLANKS 

A comment is required about ASCII characters shown 
on the screen. The ASCII code for A is 65 (decimal) 
If 65 is stored into the screen memory address, an 
INVERSE A will appear. 

If 193 (i.e. 65 + 128) is stored into this screen 
memory address, then a normal A will appear 
In HEX the comparable values are 
41 inverse A 
Cl normal A { Cl = 41 + 80) 

FILL This word is used to fill an area of memory with 

a single character of your choice. For example 

v HEX BF0O 1 41 FILL 1 location at BF00 is filled 

with an inverse A 

HEX BF0O OD Cl FILL OD (hex) locations are filled 

with a normal A 

In DECIMAL, these operations become: 

DECIMAL 48896 1 65 FILL 

DECIMAL 4 8896 13 193 FILL 

ERASE and BLANKS These words fill an area of memory with 
nulls (i.e. ASCII 0) or blanks (ASCII 32 
in decimal, 20 in hex) 

In HEX 

BF00 4 ERASE is the same as BF00 40 FILL 
BF00 40 BLANKS is the same as BF0O 40 20 FILL 
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NUMBER BASES 

Calculations may be done in any number base. 

DECIMAL sets all operations to base 10 

HEX base 16 

n BASE ! base n, where n is 2, 3, 4, etc. 

Number Base Conversions: 

To change 20 (decimal) to other bases, try this; 

VARIABLE NUM define NUM with an initial value 

DECIMAL 20 NUM .' stores number in base 10 

HEX NUM ? prints the value in base 16 

2 BASE ! NUM ? prints the value in base 2 

To change IE (hex) to other bases; 

VARIABLE NUM 
HEX IE NUM I 
DECIMAL NUM ? 
8 BASE .' NUM ? 
2 BASE I NUM ? 
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COMPARISON 



There are 5 conditional tests available. 
< * less than 
> greater than 
= equal 

0< less than zero 
0= equal to zero 

Each test destroys the number or numbers compared on 

the stack and places a value on the stack - 

1 if the condition is TRUE 

if the condition is FALSE 



Examples: (only the relevent one or two numbers on top 
of the stack are shown) 



STACK BEFORE COMPARISON STACK AFTER 

3 < 1 (true) 

2 



v 



COMPARISON 




< 




(is 


2<3 


?) 


(is 


< 
3<2 


?) 


(is 


> 
8>5 


?) 



2 < (false) 

3 

1 (true) 



5 =0 (false) 

6 (is 6 = 5 ?) 



0< (false) 

(is 1 less than zero?) 
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CONTROL STRUCTURES 

(1) DO ------ LOOP 

DO takes 2 values from the stack 

- the initial index (on top of the stack) 

- the final index PLUS 1 (next on the stack) 

E XAMPLE 5 1 DO - - - LOOP 

The count starts at 1 and ends at 4 NOT 5 

A word defined as 

: CNT 5 1 DO I . LOOP ; 

will count from 1 to 4 
where I places the current index of the loop 
on the stack and . prints this index. 
Define CNT and then type CNT to use. 

(2) DO _____ +LOOP 

The word +LOOP allows the index to change by 
any amount . 

EXAMPLE : CNT2 10 2 DO I . 2 +LOOP ; 

CNT2 will count from 2 to 8 by two's; the number 
2 just before the +LOOP gives the interval of the 
loop. 



THEN 



REPEAT 

All these structures can use the comparison words 

< > = 0< 0= 

to produce a true or false value on the stack. If a 

comparison is false, a zero is put on the stack; if 

true, a one goes on the stack. 

NOTE: The comparison words destroy the values being 

compared and replace them by a number to indicate 
true or false. 



V 








(3) 


(a) 


IF 


ELSE 




(b) 


BEGIN 


UNTIL 




(c) 


BEGIN 


WHILE 
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EXAMPLES 

(a) The IF ELSE THEN structures allows 

a choice of two branches to be taken. 

As a simple example, we shall define a word TEST 

to print whether the top value on the stack is 

positive or negative, and then print the absolute 
value. 

: TEST DUP 0< IF ." NEGATIVE " ELSE ." POSITIVE " 

THEN ABS 2 SPACES . ; 

where DUP 0< makes a copy of the number and tests if 
the copy is less than zero 

IF . " NEGATIVE " prints NEGATIVE if true 

ELSE . " POSITIVE " prints POSITIVE if false 

THEN ABS 2 SPACES . prints the absolute value of 

number 

To use, type in a number, a space, and then TEST 

The ELSE statement is optional in the structure and 
may be omitted if not required. 

(b) BEGIN UNTIL 

BEGIN marks the start of a sequence that may repeatedly 
be executed UNTIL a conditional test is false 



EXAMPLE: 



INPUT CR BEGIN KEY DUP EMIT CR 32 = 
UNTIL . " SPACE" CR ; 



where KEY puts the ASCII value of a key 

pressed onto the stack 

DUP EMIT CR makes a copy and prints the 

ASCII character onto the screen 
followed by a carriage return 

32 = tests if the ASCII value is 32 

( for a space ) 

UNTIL the structure goes back to BEGIN 
until a space is entered, then it 
prints SPACE and stops 
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To use type INPUT (then press RETURN) . Press any 
keys on the keyboard and they will be printed until 
you press the space bar. 

(c) BEGIN WHILE REPEAT 

This structure repeats while a condition test is TRUE. 

EXAMPLE 

: INPUT2 CR BEING KEY DUP 32 > WHILE EMIT 
CR REPEAT . " STOP " ; 

This example is similar to the previous one except 
the character is printed while its ASCII value is 
greater than 32. If it is not greater, then STOP is 
printed. Try using INPUT2 the same way as INPUT. 



•v 
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INPUT-OUTPUT 



String input : A string may be stored using the word 
EXPECT 



VARIABLE STR 20 ALLOT 

STR 20 BLANKS 

STR 20 EXPECT (press RETURN) 



reserves 20 spaces at 
the address STR 

clears these spaces 

waits for up to 2 
characters to be typed 
in, Pressing RETURN will 
stop the input. 



String output : 

CR STR 20 -TRAILING TYPE 



prints out the string 
stored at STR 
-TRAILING deletes any 
following blanks 



Number Formatting : 

You may wish to display numbers in certain formats, such 
as 12:24 for time displays. 

Before a number may be formatted, it must be in double 
precision form and the sign of the number must be 
stored separately. This is easily done by using DUP ABS 
before the formatting work < # 



•* 



DUP 
ABS 





makes a signed copy 

makes an unsigned number for 
formatting 

provides a dummy high order part 
for the double prevision mode 



EXAMPLES 



: N DUP ABS <# 41 HOLD #S SIGN 40 HOLD #> 
TYPE ; 

N will take a number on top of the stack and enclose 
it in brackets. 



-100 N 



will print 



(-100) 
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How N works : 

DUP ABS O prepares the single precision number 
for conversion 

<# begins the conversion 

41 HOLD since the conversion starts on the 

RIGHT the ) bracket is required first 

S all significant digits are converted 

SIGN the sign is placed on the left if 

negative 

4 HOLD the ( bracket is placed on the left 

#> the conversion ends 

TYPE the formatted number is printed 



TIME DUP ABS # # # 58 HOLD #S SIGN # TYPE 



2 34 5 TIME 



will print 



23.45 



58 HOLD 
#S 

SIGN 
#> TYPE 



begins the conversion 

the rightmost number is converted 

the next number is converted 

: is inserted 

the remaining numbers are converted 

the sign is placed on the left 

conversion ends and the number is printed 



V 
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Miscellaneous Words 



VLIST prints the words in the dictionary, 

starting with the most recent definition 



FORGET deletes definitions up to and including 

the definition named 



Advanced topics such as VOCABULARIES, CODE definitions 

and the construction < BUILDS DOES > will be 

treated in future manual updates and newsletters. 



v 
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EDITOR WORDS 

The lower case letters before a definition represent 
an address or number to be entered before the word is 
used. Address locations are usually given in hex; 
type HEX before the number is entered. When you wish 
to return to base 10, type DECIMAL 



addr TEXTSTART - allows the user to define the memory 
location for the start of the text, 
e.g. HEX B800 TEXTSTART 



n BLOCKS 



TEXT? 



TEXTCLEAR 



defines blocks of 128, fi bytes 
beginning with the location of 
TEXTSTART . 

e.g. 8 BLOCKS uses memory from 
B80 to BBFF 

prints the start address of text 
and the number of blocks assigned 

fills all blocks with blanks; this 
word is used when setting up the 
EDITOR 



n B/CLR 
n B/VIEW 

n B/REV 

V 

n B/COMP 
n B/INS 



n B/DEL 



- fills block n with blanks 

- displays the contents of block n 
near the centre of the screen ready 
for entering or altering text 

- displays the contents of block n near 
the top of the screen for review only. 
NO editing is done in this part of the 
screen. 

- compiles the text of block n 

- inserts a blank block at n and moves 
the following blocks up one; the last 
block must be clear or an error 
message will occur. 

e.g. before 12345678 (8 is blank) 
* "■* ""^ Ns. -^ Ni. >s 

2 B/INS 12 3 4 5 6 7 8 (2 is blank) 

- deletes block n and moves the following 
blocks down one 

e.g. before 12345678 

3 B/DEL 12345678 (8 now 

blank) 
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- begins entry or alteration of text 
in a block 



NOTE : 



NOTE: 



this work should be preceeded 
by n B/VIEW so that you are 
editing the correct block, 
e.g. 3 B/VIEW { 

The cursor may be moved within 
the bock using: 

CTRL E - up 

CTRL X - down 

CTRL D - right 

CTRL S - left (avoid using 

BACKSPACE) 
RETURN - new line 



ends the entry or editing of text 
in a block 



- views next page 



TEXTCOMP 



TEXTSAVE 



TEXTLOAD 



- vxews previous page 

- compiles all text from block 1 onwards, 
Each block will be displayed as it is 
compiled. An error in a definition 
will stop the compilation. Remember 
to FORGET any definitions you are 
recompiling or you will get a REDEF 
NOT UNIQUE message. 

- saves all blocks on cassette tape; a 
file name is requested 

- loads text from cassette tape into 
the memory specified by TEXTSTART 
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USING THE EDITOR 

For a system with 4K of RAM a suitable location to 
store text would be from B8 00 to BBFF - 8 blocks. 
The compiled FORTH definitions will be stored from 
the beginning of the Dictionary space upwards; the 
average program should easily fit in this space up 
to B7FF. The RAM above BC00 is used for the stack 
and system parameters. 

To begin, use TEXTSTART BLOCKS TEXTCLFAR 

For example HEX B800 TEXTSTART 8 BLOCKS 

DECIMAL to return to base 10 - 

TEXTCLEAR to clear all blocks 

1 B/VIEW to view block 1 

} to begin editing 

Now enter text, using the CTRL keys and RETURN to 

move the cursor. The word ( ends the entry or 

alteration of text. 

Block 1 will now contain any text you have entered. 
Definitions may be from 1 to 4 lines long. Begin a 
new line for each new definition. If you are starting 
a new definition, be certain you will have enough space 
o^else begin the next block. The compiling ignores 
any blank lines. Blank lines are often useful for 
inserting changes later. 

To display block 1 at the top of the screen, type 1 
B/REV Now you can type 2 B/VIEW \ to enter text to block 
2 while still displaying block 1. You may display any 
block for revision while you are working on another block. 
Continue entering text until you are ready to test your 
definitions. You may compile and test a block at a time, 
beginning with block 1 using B/COMP or you may compile 
the entire text with TEXTCOMP . If you wish to make 
alterations, clear the screen CLS and use B/VIEW and 
to edit any block. Then FORGET back to the first 
definition you changed and recompile that block and 
those following. 
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SAVING and LOADING TEXT 

To save FORTH text, use TEXTSAVE A file name will be 
requested. The file name can be 8 characters long, 
but it is suggested to use .F as the last two 
characters to specify FORTH text. e.g. FILENAME? 
PROGRl.F 

To save a compiled FORTH program, use SAVE as 
explained in the FORTH manual. Use .C for the end 
of the filename. It is always advisable to save text 
so you can make later revisions. If you only save the 
compiled program, any alterations may mean extensive 
retyping. 

One option is to save the TEXT on one side of a 
cassette, and the compiled version on the other. The 
compiled version will load faster and free the text 
space for other text or programs. 



To load text, use TEXTLOAD , to load the compiled 
version use LOAD. 



V, 
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DFORTII 

If you define words without the use of the FORTH 
1.2 text EDITOR, you lose the text for the definition 
when it scrolls off the screen. Quite often it is 
necessary to recall these definitions. This recall 
may be done using DFORTH. 

e.g. DFORTH PROG will give the text of your 

definition for the word PROG 

HOWEVER, there are certain limitations: 

1) definitions should be kept simple. For example 
you should not combine IF ELSE THEN 

or BEGIN END 

or BEGIN IF AGAIN 

or DO LOOP in one definition. 
Instead, use a separate word for each structure 
required and then combine these new words into an 
additional word, 
e.g. : INPUT BEGIN KEY DDP EMIT 32 = UNTIL ; 

: PHRASE 5 1 DO INPUT LOOP CR ; 

PHRASE will input 4 words from the keyboard each 
separated by a space. 

2) definition containing ." " to print 
characters may take several seconds to DFORTH (be 
patient) . Again, keep this construction separate from 
the others in 1) above. 

3) certain synonyms are possible for words 

IF ELSE THEN reappears as IF ELSE ENDIF 

BEGIN UNTIL BEGIN END 

BEGIN IF AGAIN BEGIN WHILE REPEAT 

If DFORTH should get 'hung up' , possibly because of a 
faulty definition, or a word that is too complex, refer 
to E - 1.0 under the heading PANIC 



